home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / julin105.zip / DOC / READ.ME next >
Text File  |  1993-08-02  |  15KB  |  390 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                               JULIAN DATE LIBRARY
  24.                                v:1.05 d:08/02/93
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.                                  Robert Emmons
  52.                                  CalcShop Inc.
  53.                                   P.O Box 1231
  54.                              W. Caldwell, NJ  07007
  55.                      Phones: (201)228-9139 or (800)466-3469
  56.  
  57.              JULIAN DATE LIBRARY (c)Copyright 1992 by CalcShop Inc.
  58.                               All rights reserved.
  59.  
  60.  
  61.     1.00 GENERAL:
  62.  
  63.     JULIAN provides a library of date routines which are useful in financial
  64.     and other types of programs. The functions are written in C, and they
  65.     allow you to translate dates between the following formats:
  66.  
  67.     Name                Format                          Example
  68.     ------              ----------------------------    -----------
  69.     Gregroian string    "mm/dd/yy"                      9/12/92
  70.     Gregorian string    "mm/dd/yyyy"                    9/12/1992
  71.     Gregorian           struct{int month, day, year}    9, 12, 1992
  72.     Julian              long julianday                  727453
  73.  
  74.     So, why would you want to do that? Well, programs like Lotus, FoxPro,
  75.     and dBASE store dates internally as Julian day numbers. This makes it
  76.     easy to do date arithmetic. You can calculate the number of days between
  77.     any two dates, the day of the week for a particular date, or the date of
  78.     the day which is some number of days in the future. Almost all date
  79.     calculations are easier to do when you work with Julian day numbers
  80.     instead of the more commonly seen Gregorian calendar dates and their
  81.     string representations. Consequently, well written programs store dates
  82.     internally as Julian day numbers, and only translate the dates to
  83.     Gregorian or string when they have to input or output them. If you use
  84.     our JULIAN library, your programs can do the same.
  85.  
  86.     JULIAN numbers all days sequentially starting with 1/1/0001 A.D. as
  87.     Julian day number 1, and ending with 12/31/9999 A.D. as Julian day
  88.     number 3652059. As you may guess from the table above, 9/12/1992 is
  89.     Julian day number 727453.
  90.  
  91.     Other systems use different days as day number 1:
  92.  
  93.         System          Day number 1    To Convert to FoxPro, Add
  94.         -------         -------------   -------------------------
  95.         JULIAN          1/1/0001 A.D.   1721425
  96.         Astronomical    1/1/4713 B.C.   0
  97.         FoxPro          1/1/4713 B.C.   0
  98.         Lotus           1/1/1899 A.D.   2415918
  99.  
  100.     Purists prefer the FoxPro definition because astronomers also define
  101.     1/1/4713 B.C. as day number 1. You can convert between systems by adding
  102.     or subtracting the constant shown in the table, as long as the specified
  103.     date is within the range over which the system is defined.
  104.  
  105.  
  106.     JULIAN is fully corrected for leap years which occur when the Gregorian
  107.     year is evenly divisable by 400, or when it is evenly divisable by 4 and
  108.     not by 100.
  109.  
  110.     Calendar systems in the past were not as accurate ours. There were
  111.     several instances where the seasons got out of synchronism with the
  112.     dates predicted by the calendar. Consequently, dates were sometimes
  113.     changed arbitrarily. (Like "The King says this March will only have
  114.     18 days. March 18th will be immediately followed by April 1.").
  115.     Julian does not correct for these past arbitrary calendar changes.
  116.     There would seem to be no reason to make the corrections unless you
  117.     need dates for historical purposes before the year 1900.
  118.  
  119.  
  120.     2.00 REGISTRATION and TECHNICAL SUPPORT
  121.  
  122.     The JULIAN library is not free. After you try it and decide to continue
  123.     to use it, you must pay the registration fee. See the registration form
  124.     at the end of this document.
  125.  
  126.     Anyone can copy all the JULIAN DATE LIBRARY files, and distribute it
  127.     freely so others can try it before registering their copy.
  128.  
  129.     We also do custom programming for investments, finance and accounting.
  130.  
  131.     For technical support, questions or comments, call (201)228-9139 or
  132.     write to the address above. Please do not call for technical support on
  133.     the 800 line.
  134.  
  135.  
  136.  
  137.  
  138.     3.00 FILE LIST
  139.  
  140.     The distribution disk contains 6 files:
  141.  
  142.             JULIAN.C        Source code for the library
  143.             JULDEF.H        Definitions and prototypes
  144.             JULDEMO.C       Source code showing use of JULIAN functions
  145.             JULDEMO.EXE     Executable JULDEMO
  146.             READ.ME         This file
  147.             REGISTER.DOC    A program registration form
  148.  
  149.  
  150.  
  151.  
  152.     4.00 INSTALLATION
  153.  
  154.     Make a directory and copy all the files into it from the distribution
  155.     disk. The information below and the source code from JULDEMO.C should
  156.     show you how to call the JULIAN library functions from your own C code.
  157.  
  158.     You can use one of 2 methods to include the JULIAN library in your
  159.     programs. You can use your program editor to insert JULIAN.C into
  160.     your program file and compile and link the file to produce and
  161.     executable .EXE file. Alternatively, compile your program and JULIAN.C
  162.     separately. Then, when you link your program, link in JULIAN.OBJ, or
  163.     list JULIAN.OBJ in your project file.
  164.  
  165.  
  166.     5.00 USING JULDEMO
  167.  
  168.     Switch to the appropriate directory and type JULDEMO. You will be
  169.     prompted for dates, and they will be conveted to and from Julian day
  170.     numbers, and displayed. See the source code in JULDEMO.C.
  171.  
  172.     If you start JULDEMO by entering "juldemo a", the demo runs in
  173.     "automatic" mode. It will read, convert and display a preprogrammed set
  174.     of string representations of Gregorian dates.
  175.  
  176.  
  177.  
  178.  
  179.     6.00 DESCRIPTION OF THE JULIAN FUNCTIONS
  180.  
  181.     See JULDEF.H for definitions and function prototypes.
  182.  
  183.     The JULIAN library defines a Gregorian date type:
  184.  
  185.     typedef struct gregorian
  186.     {
  187.         int month, day, year;
  188.     } GDATE;
  189.  
  190.  
  191.     There are just 2 main conversion functions in the JULIAN library:
  192.  
  193.     Function                Description
  194.     --------                -----------
  195.     long gregtojday(GDATE)  converts a Gregorian date to a Julian day number
  196.     GDATE jdaytogreg(long)  convetts a Julian day number to a Gregorian date
  197.  
  198.  
  199.  
  200.     There are just 2 input/output functions in the JULIAN library:
  201.  
  202.         Function                    Description
  203.         --------                    -----------
  204.         GDATE mmddyyyytogreg(       converts a string date to a Gregorian
  205.             char *str,              structure
  206.             int nearyear
  207.         )
  208.         char *gregtommddyyyy(       converts a Gregorian structure to a
  209.             char *str,              date
  210.             GDATE gdate,
  211.             int nearyear
  212.         )
  213.  
  214.  
  215.     The other functions in the JULIAN library are called as subfunctions
  216.     from the main funcions above. Although you probably won't need them,
  217.     they are supplied just in case.
  218.  
  219.  
  220.  
  221.     gregtojday() translates a Gregorian date between 1/1/0001 A.D and
  222.     12/31/9999 to a Julian day number between 1 and 3652059. Those of you
  223.     needing B.C. dates, consult your abacus.
  224.  
  225.  
  226.     gregtojear() translates a Gregorian date to a Julian pseudoyear. This is
  227.     a function which you probably won't need, but for you "Star Trek"
  228.     fans, a Julian pseudoyear is kind of like a "Star Date". It is a double
  229.     whose whole number part is almost always equal to the corresponding
  230.     Gregorian year, while its fractional part is approximately equal to the
  231.     corresponding year day divided by 365. The existence of leap years
  232.     prevents unconditional exact equality. The Julian pseudoyear is equal
  233.     one plus (the corresponding Julian day divided by the average number of
  234.     days in a year). The average number of days in a year takes into account
  235.     the full cycle of leap years over 4 centuries.
  236.  
  237.  
  238.     Here are some sample Julian pseudoyears:
  239.  
  240.         Gregorian        Julian      Julian
  241.